Execute shell commands and ARexx macros

AWeb offers a unique and powerful facility to execute Amiga DOS Shell commands and ARexx macros from a page, just by clicking on a hyperlink or by submitting a form. With some effort, you can create complex applications using AWeb as the user interface, starting scripts that dynamically compose new documents that are loaded into AWeb via ARexx, etcetera.

Although this feature can be very useful, it could also be very dangerous. Therefore this feature works only from local pages (with a URL starting with file://localhost/), and only if the Allow Shell commands setting is selected.

Simple shell commands

To include a simple command, just add a normal hyperlink in your document that points to a URL of the form

   x-aweb:command/your_DOS_command

If the user clicks on the hyperlink, your_DOS_command is executed. The output of the command is directed to an auto opening console window, unless you specify another output redirection in your command.

Because compatible HTML mode stops the URL at a space, make sure you have escaped all spaces in the command by " " or else the command won't work if the user has selected compatible HTML mode.

Example: <a href="x-aweb:command/dir sys: all">get dir</a> would allow the user to execute the dir sys: all command by a click on the words "get dir".

Note: The DOS command is executed in a separate shell, with a current directory set equal to the current directory of AWeb. You are advised to use only absolute path names in the DOS command, or else the result will depend on which directory happened to be the current directory when you started AWeb.

ARexx macros

Starting ARexx macros from your page works in a similar way. Just add a normal hyperlink that points to a URL of the form

   x-aweb:rexx/your_ARexx_macro

If the user clicks on the hyperlink, your_ARexx_macro is started with the ARexx port for this window as the default command port.

Parameters

You can use a HTML form or a clickable map to pass parameters to your DOS command or ARexx macro.

Forms

Supply a ACTION="x-aweb:command/your_command" attribute in your <FORM> tag to execute the command if the user submits the form. Similarly, you can include a ACTION="x-aweb:rexx/your_macro" attribute to start the ARexx macro.

Form parameters are converted to Amiga DOS style parameters: the field name will be used as the argument name, and the field value will be used as argment value. The value will be quoted, with the escape, newline and quote characters in the value escaped as required by Amiga DOS.

Note: switch arguments (/S) cannot be passed in this way. You could use a script instead, like the example below.

Clickable maps

When using a clickable map, the x and y coordinates of the mouse pointer within the image are passed to the command as parameters without keyword.

ARexx arguments

Parameters for ARexx macros are passed in the same format as for DOS scripts. The argument string will contain the name, an equal sign, and a quoted value for each form parameter. Have a look at the second example below for one possible way of parsing this.

Load the result back into AWeb

If your script or macro has created a HTML document (or just a plain text file), you can automatically load this file back into AWeb. Use the ARexx OPEN command for this purpose. If you re-use the name of your file for different responses, be sure to add the RELOAD switch to prevent AWeb from showing the previous (cached) document again.

Of course, this will work better from within an ARexx macro than from within a DOS script. In a DOS script, you have no way of determining to which ARexx port you should address the OPEN command.

Examples

Below are two examples of this feature. Have a look at the source of this page, and at the executed macro first to convince yourself that following the link or submitting the form won't do any harm. Then select Allow Shell commands in the settings requester and play with this form.

Simple shell command

This example just gets the directory of SYS: and shows it in a separate console window: show dir.

ARexx macro

This example gets the directory contents of a selected drawer.